<div class="section" id="section.SwitchingXMLProcessors"
     xmlns="http://www.w3.org/1999/xhtml">
    <div class="title">Switching XML processors</div>
    <div class="content">

        <p>
            All control and event UPnP messages have an XML payload, and the control messages are even
            wrapped in SOAP envelopes. Handling XML for control and eventing is encapsulated in the Cling
            transport layer, with an extensible service provider interface:
        </p>

        <dl>
            <dt><code>org.fourthline.cling.transport.spi.SOAPActionProcessor</code></dt>
            <dd>
                This processor reads and writes UPnP SOAP messages and transform them from/to
                <code>ActionInvocation</code> data. The protocol layer, on top of the transport layer,
                handles <code>ActionInvocation</code> only.
            </dd>
            <dt><code>org.fourthline.cling.transport.spi.GENAEventProcessor</code></dt>
            <dd>
                This processor reads and writes UPnP GENA event messages and transform them
                from/to a <code>List&lt;StateVariableValue></code>.
            </dd>
        </dl>

        <p>
            For the <code>SOAPActionProcessor</code>, the following implementations are bundled
            with Cling Core:
        </p>

        <dl>
            <dt><code>org.fourthline.cling.transport.impl.SOAPActionProcessorImpl</code> (default)</dt>
            <dd>
                This implementation reads and writes XML with the JAXP-provided DOM API provided by JDK 6.
                You do not need any additional libraries to use this processor. However, its strict compliance
                with the UPnP specification can cause problems in real-world UPnP applications. This processor
                will produce errors during reading when XML messages violate the UPnP specification. Use it
                to test a UPnP stack or application for strict specification compliance.
            </dd>
            <dt><code>org.fourthline.cling.transport.impl.PullSOAPActionProcessorImpl</code></dt>
            <dd>
                This processor uses the XML Pull API to read messages, and the JAXP DOM API to write messages.
                You need an implementation of the XML Pull API on your classpath to use this processor, for
                example, <a href="http://www.extreme.indiana.edu/xgws/xsoap/xpp/mxp1/index.html">XPP3</a>
                or <a href="http://kxml.sourceforge.net/kxml2/">kXML 2</a>. Compared with the default processor,
                this processor is much more lenient when reading action message XML. It can deal with broken
                namespacing, missing SOAP envelopes, and other problems. In UPnP applications where
                interoperability is more important than specification compliance, you should use this parser.
            </dd>
            <dt><code>org.fourthline.cling.transport.impl.RecoveringSOAPActionProcessorImpl</code></dt>
            <dd>
                This processor extends the <code>PullSOAPActionProcessorImpl</code> and additionally will
                work around known bugs of UPnP stacks in the wild and try to recover from parsing failures by
                modifying the XML text in different ways. This is the processor you should use for best
                interoperability with other (broken) UPnP stacks. Furthermore, it let's you handle a failure
                when reading an XML message easily by overriding the <code>handleInvalidMessage()</code> method,
                e.g. to create or log an error report. It is the default processor for
                <code>AndroidUpnpServiceConfiguration</code>.
            </dd>
        </dl>

        <p>
            For the <code>GENAEventProcessor</code>, the following implementations are bundled
            with Cling Core:
        </p>

        <dl>
            <dt><code>org.fourthline.cling.transport.impl.GENAEventProcessorImpl</code> (default)</dt>
            <dd>
                This implementation reads and writes XML with the JAXP-provided DOM API provided by JDK 6.
                You do not need any additional libraries to use this processor. However, its strict compliance
                with the UPnP specification can cause problems in real-world UPnP applications. This processor
                will produce errors during reading when XML messages violate the UPnP specification. Use it
                to test a UPnP stack or application for strict specification compliance.
            </dd>
            <dt><code>org.fourthline.cling.transport.impl.PullGENAEventProcessorImpl</code></dt>
            <dd>
                This processor uses the XML Pull API to read messages, and the JAXP DOM API to write messages.
                You need an implementation of the XML Pull API on your classpath to use this processor, for
                example, <a href="http://www.extreme.indiana.edu/xgws/xsoap/xpp/mxp1/index.html">XPP3</a>
                or <a href="http://kxml.sourceforge.net/kxml2/">kXML 2</a>. Compared with the default processor,
                this processor is much more lenient when reading action message XML. It can deal with broken
                namespacing, missing root element, and other problems. In UPnP applications where
                compatibility is more important than specification compliance, you should use this parser.
            </dd>
            <dt><code>org.fourthline.cling.transport.impl.RecoveringGENAEventProcessorImpl</code></dt>
            <dd>
                This processor extends the <code>PullGENAEventProcessorImpl</code> and additionally will
                work around known bugs of UPnP stacks in the wild and try to recover from parsing failures by
                modifying the XML text in different ways. This is the processor you should use for best
                interoperability with other (broken) UPnP stacks. Furthermore, it will return partial results,
                when at least one single state variable value was successfully read from the event XML.
                It is the default processor for <code>AndroidUpnpServiceConfiguration</code>.
            </dd>
        </dl>

        <p>
            You can switch XML processors by overriding the <code>UpnpServiceConfiguration</code>:
        </p>

        <pre><![CDATA[UpnpService upnpService = new UpnpServiceImpl(
    new DefaultUpnpServiceConfiguration() {

        @Override
        public SOAPActionProcessor getSoapActionProcessor() {
            // Recommended for best interoperability with broken UPnP stacks!
            return new RecoveringSOAPActionProcessorImpl();
        }

        @Override
        public GENAEventProcessor getGenaEventProcessor() {
            // Recommended for best interoperability with broken UPnP stacks!
            return new RecoveringGENAEventProcessorImpl();
        }
    }
);]]></pre>
    </div>
</div>